urlaccesstransfer.htmlHTMLudogÙ¸πùΔ§πùΔ§ÅÅ4fl Monkeybread Realbasic plugin - Documentation - URLAccessTransfer

MBS Plugin Documentation

This is the documentation for the Realbasic Plugins from Monkeybreadsoftware.de. You find these plugins and the newest version of this document at http://www.monkeybreadsoftware.de/realbasic inside the plugins section.

This help was last updated on Freitag, 6. September 2002 and covers 2136 items: 126 classes, 2 controls and 583 global functions.

The list of the themes Global methods by category Global methods by name The list of the classes The list of the controls

class URLAccessTransfer
class, URLAccess Mi, 4. Sep 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: does nothing.
Function: A complex URLAccess download.
Notes: Requires URLAccess extension.

Abort
method, URLAccess Mi, 4. Sep 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: Never called.
Function: Aborts the download.
Notes:
The Abort function terminates any data transfer operation started by the functions Download, Upload, or Open. When your application calls Abort, the URL Access Manager changes the state returned by the function GetCurrentState to kURLAbortingState and calls the Aborting event. When data transfer is terminated, the URL Access Manager changes the state returned by GetCurrentState to kURLCompletedState and calls the Completed event.

Lasterror is set.

Aborting
event, URLAccess Mi, 4. Sep 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: Never called.
Function: Indicates that a download or upload operation is aborting.

Completed
event, URLAccess Mi, 4. Sep 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: Never called.
Function: Indicates that there is no more activity to be performed on this stream.

Connecting
event, URLAccess Mi, 4. Sep 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: Never called.
Function: Connecting to target server.

CurrentSize as integer
property, URLAccess Mi, 4. Sep 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: Allways 0.
Function: The current download size.

CurrentState as integer
method, URLAccess Mi, 4. Sep 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: Never called.
Function: Returns the current state.
Notes:
Possible values:

kURLNullState = 0

Indicates that the function Open has not yet been called.

kURLInitiatingState = 1

Indicates that the function Open has been called, but the location specified by the URL reference has not yet been accessed. The stream enters this state from the kURLNullState state.

kURLLookingUpHostState = 2

Indicates that the function Open has been called, and that the host is being looked up. The stream enters this state from the kURLInitiatingState state.

kURLConnectingState = 3

Indicates that the function Open has been called, and a connection is being made. The stream enters this state from the kURLLookingUpHostState state.

kURLResourceFoundState = 4

Indicates that the location specified by the URL reference has been accessed and is valid. The stream enters this state from the kURLConnectingState state.

kURLDownloadingState = 5

Indicates that the download operation is in progress but there is currently no data in the buffers. The stream enters this state initially from the kURLResourceFoundState state. During a download operation, the stream’s state may alternate between the kURLDownloadingState and the kURLDataAvailableState states.

kURLDataAvailableState = 21

Indicates that the download operation is in progress and data is available in the buffers. The stream initially enters this state from the kURLDownloadingState state. During a download operation, the stream’s state may alternate between the kURLDownloadingState and the kURLDataAvailableState states. If the stream is in the data available state, you may want to call the function DataAvailable to determine the amount of data available for download. If you pass NULL in the fileSpec parameter of the function Open, you will need to call the function URLGetBuffer to obtain the next buffer of data.

kURLTransactionCompleteState = 6

Indicates that a download or upload operation is complete. The stream can enter this state from the kURLDownloadingState state.

kURLErrorOccurredState = 7

Indicates that an error occurred during data transfer. The stream can enter this state from any state except the kURLAbortingState state. If the stream is in this state, you may wish to call the function URLGetError to determine the nature of the error.

kURLAbortingState = 8

Indicates that a download or upload operation is aborting. The stream enters this state from the kURLErrorOccurredState state or as a result of calling the function Open when the stream is in any other state. When your application calls the function Abort, the URL Access Manager changes the state returned by the function URLGetCurrentState to kURLAbortingState and passes the constant kURLAbortInitiatedEvent to your notification callback function.

kURLCompletedState = 9

Indicates that there is no more activity to be performed on this stream. In this case, the data transfer has either completed successfully or been aborted. The stream enters this state from the kURLTransactionCompleteState or the kURLAbortingState state. When data transfer is terminated after a data transfer operation is aborted, the URL Access Manager changes the state returned by CurrentState to kURLCompletedState and passes the constant kURLCompletedEvent in the event parameter of your notification callback function.

kURLUploadingState = 10

Indicates that an upload operation is in progress.


Lasterror is set.

DataAvailable
event, URLAccess Mi, 4. Sep 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: Never called.
Function: Indicates that the download operation is in progress and data is available in the buffers.

DataAvailable as integer
method, URLAccess Mi, 4. Sep 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: Never called.
Function: Is data available?
Notes:
Returns the number of bytes inside the download buffer.

Lasterror is set.

DirectoryListing as boolean
property, URLAccess Mi, 4. Sep 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: does nothing.
Function: Return directory listing?

DisplayAuth as boolean
property, URLAccess Mi, 4. Sep 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: does nothing.
Function: Display an authorisation box?
Notes: The URL may contain a username and a password.

DisplayProgress as boolean
property, URLAccess Mi, 4. Sep 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: does nothing.
Function: Display an progress bar dialog?

DoNotTryAnonymous as boolean
property, URLAccess Mi, 4. Sep 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: does nothing.
Function: Do not try anonymous?
Notes: The URL may contain a username and a password.

Download
method, URLAccess Mi, 4. Sep 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: does nothing.
Function: Downloads a file.
Notes:
The property URL is used for the URL to the file you want to download.

File is a folderitem that identifies the file or directory into which data is to be downloaded. If you wish to download data into memory, pass nil in this parameter and the data will be put into the result property. If you pass a folderitem that does not identify a file or directory, the name of the file or directory specified by the pathname in the url parameter is used. If you pass a file or directory that already exists, and do ReplaceExisting is false, URLSimpleDownload creates a new file or directory whose name has a number appended before the extension. For example, if the URL specifies a file named file.txt, URLSimpleDownload changes the filename to file1.txt.

This function does not return until the download is complete.
See the lasterror property for the error code returned.

When Download downloads data from a URL that represents a local file (that is, a URL that begins with file:///), the data fork is downloaded but the resource fork is not.

In Mac OS 8.6, if the file type of the file to be downloaded is unknown, Download assumes that the file is of type text. In this case, the end-of-line character is changed to the Mac style end-of-line character 0x0d0x0a. In Mac OS 9, when a file of unknown type is downloaded, Download does not assume that it is a text file. Instead, it identifies it as an unknown file type and does not change the end-of-line character.

Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 8.1 or later.

Downloading
event, URLAccess Mi, 4. Sep 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: Never called.
Function: Indicates that the download operation is in progress but there is currently no data in the buffers.

Error as integer
event, URLAccess Mi, 4. Sep 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: Never called.
Function: Determines the error code of a failed data transfer operation.
Notes:
Possible URLAccess error codes:

InvalidURLReferenceError -30770
ProgressAlreadyDisplayedError -30771
DestinationExistsError -30772
InvalidURLError -30773
UnsupportedSchemeError -30774
ServerBusyError -30775
AuthenticationError -30776
PropertyNotYetKnownError -30777
UnknownPropertyError -30778
PropertyBufferTooSmallError -30779
UnsettablePropertyError -30780
InvalidCallError -30781
FileEmptyError -30783
ExtensionFailureError -30785
InvalidConfigurationError -30786
AccessNotAvailableError -30787
68kNotSupportedError -30788

ExpandAndVerify as boolean
property, URLAccess Mi, 4. Sep 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: does nothing.
Function: Expand and verify?
Notes: Using Stuffit Expander.

ExpandFile as boolean
property, URLAccess Mi, 4. Sep 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: does nothing.
Function: Expand file?
Notes: Using Stuffit Expander.

File as folderitem
property, URLAccess Mi, 4. Sep 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: Allways nil.
Function: A reference to a file or folder.

Handle as integer
property, URLAccess Mi, 4. Sep 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: Allways 0.
Function: A handle to the used URLReference.

Idle
event, URLAccess Mi, 4. Sep 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: Never called.
Function: Idle event of the URLAccess function.

Initiating
event, URLAccess Mi, 4. Sep 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: Never called.
Function: A transfer was initiated, but nothing has been done yet.

IsDirectoryHint as boolean
property, URLAccess Mi, 4. Sep 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: does nothing.
Function: Exspect a directory?

LastError as integer
property, URLAccess Mi, 4. Sep 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: Allways 0.
Function: The last error code.
Notes:
Lasterror may have any Mac OS error code, but the functions return -1 if the URLAccess library is not available.

Possible URLAccess error codes:

InvalidURLReferenceError -30770
ProgressAlreadyDisplayedError -30771
DestinationExistsError -30772
InvalidURLError -30773
UnsupportedSchemeError -30774
ServerBusyError -30775
AuthenticationError -30776
PropertyNotYetKnownError -30777
UnknownPropertyError -30778
PropertyBufferTooSmallError -30779
UnsettablePropertyError -30780
InvalidCallError -30781
FileEmptyError -30783
ExtensionFailureError -30785
InvalidConfigurationError -30786
AccessNotAvailableError -30787
68kNotSupportedError -30788

LookingUpHost
event, URLAccess Mi, 4. Sep 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: Never called.
Function: The Domain is being resolved.

Open
method, URLAccess Mi, 4. Sep 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: Never called.
Function: Opens a URL and starts an asynchronous download or upload operation.
Notes:
The Open function starts a download or upload operation and returns control to your application immediately. For download operations, you do not have to specify a valid destination file. In this case, you should call the function ReadAll repeatedly to get the next buffer of data. Between calls to ReadAll, you should call the function URLAccessIdle to allow time for the URL Access Manager to refill its buffers during download operations. You can call the function DataAvailable to determine the amount of data remaining in the buffer of the URL Access Manager that you will obtain from a call to the function ReadAll.

If you pass a valid destination file, you should not call the functions ReadAll or DataAvailable.

When Open downloads data from a URL that represents a local file (that is, a URL that begins with file:///), the data fork is downloaded but the resource fork is not.

In Mac OS 8.6, if the file type of the file to be uploaded or downloaded is unknown, Open assumes that the file is of type text. In this case, the end-of-line character is changed to the Mac style end-of-line character 0x0d0x0a. In Mac OS 9, when a file of unknown type is uploaded or downloaded, URLOpen does not assume that it is a text file. Instead, it identifies it as an unknown file type and does not change the end-of-line character.

Lasterror is set.

Other(eventcode as integer)
event, URLAccess Mi, 4. Sep 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: Never called.
Function: Currently this event is never called, but maybe Apple will introduce a new event code in the future this event will help you.

pAuthType as integer
property, URLAccess Mi, 4. Sep 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: Allways 0.
Function: The authorisation type for this transfer.
Notes: URLAccess stores itself properties about this transfer which you can access (read and write) using the properties of this RB class which starts with a "p".

pCertificate as string
property, URLAccess Mi, 4. Sep 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: Allways false.
Function: The Certificate used.
Notes: URLAccess stores itself properties about this transfer which you can access (read and write) using the properties of this RB class which starts with a "p".

pCharacterSet as string
property, URLAccess Mi, 4. Sep 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: Allways "".
Function: The character code of the file to download.
Notes: URLAccess stores itself properties about this transfer which you can access (read and write) using the properties of this RB class which starts with a "p".

pConnectTimeout as integer
property, URLAccess Mi, 4. Sep 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: Allways "".
Function: The time out value for this connection.
Notes: URLAccess stores itself properties about this transfer which you can access (read and write) using the properties of this RB class which starts with a "p".

Percent
event, URLAccess Mi, 4. Sep 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: Never called.
Function: Called for every percent which is downloaded.
Notes: If a buffer is received and the new position reaches a new percent, this event is called. This may be 3 times on a 30 K file, so don't exspect 100 calls. You may update a progress bar in this case.

Periodic
event, URLAccess Mi, 4. Sep 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: Never called.
Function: Called on a periodic time interfall so you can update interface.

pFileCreator as string
property, URLAccess Mi, 4. Sep 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: Allways "".
Function: The file creator code of the file to download.
Notes: URLAccess stores itself properties about this transfer which you can access (read and write) using the properties of this RB class which starts with a "p".

pFileType as string
property, URLAccess Mi, 4. Sep 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: Allways "".
Function: The file type of the file to download.
Notes: URLAccess stores itself properties about this transfer which you can access (read and write) using the properties of this RB class which starts with a "p".

pHost as string
property, URLAccess Mi, 4. Sep 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: Allways "".
Function: The name of the host of the item to download.
Notes: URLAccess stores itself properties about this transfer which you can access (read and write) using the properties of this RB class which starts with a "p".

pHTTPRedirectedURL as string
property, URLAccess Mi, 4. Sep 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: Allways "".
Function: The HTTP redirected URL string.
Notes: URLAccess stores itself properties about this transfer which you can access (read and write) using the properties of this RB class which starts with a "p".

pHTTPRequestBody as string
property, URLAccess Mi, 4. Sep 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: Allways "".
Function: The HTTP Request body.
Notes: URLAccess stores itself properties about this transfer which you can access (read and write) using the properties of this RB class which starts with a "p".

pHTTPRequestHeader as string
property, URLAccess Mi, 4. Sep 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: Allways "".
Function: The HTTP Request header.
Notes: URLAccess stores itself properties about this transfer which you can access (read and write) using the properties of this RB class which starts with a "p".

pHTTPRequestMethod as string
property, URLAccess Mi, 4. Sep 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: Allways "".
Function: The HTTP Request method.
Notes: URLAccess stores itself properties about this transfer which you can access (read and write) using the properties of this RB class which starts with a "p".

pHTTPRespHeader as string
property, URLAccess Mi, 4. Sep 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: Allways "".
Function: The HTTP response header.
Notes: URLAccess stores itself properties about this transfer which you can access (read and write) using the properties of this RB class which starts with a "p".

pHTTPUserAgent as string
property, URLAccess Mi, 4. Sep 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: Allways "".
Function: The HTTP user agent string.
Notes: URLAccess stores itself properties about this transfer which you can access (read and write) using the properties of this RB class which starts with a "p".

pIsSecure as boolean
property, URLAccess Mi, 4. Sep 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: Allways false.
Function: Wether this is a secure transfer. (SSL)
Notes: URLAccess stores itself properties about this transfer which you can access (read and write) using the properties of this RB class which starts with a "p".

pLastModifiedTime as integer
property, URLAccess Mi, 4. Sep 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: Allways "".
Function: The last modified time value.
Notes: URLAccess stores itself properties about this transfer which you can access (read and write) using the properties of this RB class which starts with a "p".

pMIMEType as string
property, URLAccess Mi, 4. Sep 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: Allways "".
Function: The mime type of the file to download.
Notes: URLAccess stores itself properties about this transfer which you can access (read and write) using the properties of this RB class which starts with a "p".

pPassword as string
property, URLAccess Mi, 4. Sep 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: Allways "".
Function: The password for this transfer.
Notes: URLAccess stores itself properties about this transfer which you can access (read and write) using the properties of this RB class which starts with a "p".

pResourceName as string
property, URLAccess Mi, 4. Sep 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: Allways "".
Function: The resourcename of the item to download.
Notes: URLAccess stores itself properties about this transfer which you can access (read and write) using the properties of this RB class which starts with a "p".

pResourceSize as integer
property, URLAccess Mi, 4. Sep 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: Allways "".
Function: The Size of the object to download.
Notes: URLAccess stores itself properties about this transfer which you can access (read and write) using the properties of this RB class which starts with a "p".

PropertyChanged(property as string)
event, URLAccess Mi, 4. Sep 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: Never called.
Function: Called whenever a property changed.

pSSLCipherSuite as string
property, URLAccess Mi, 4. Sep 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: Allways "".
Function: The SSL cipher suite string.
Notes: URLAccess stores itself properties about this transfer which you can access (read and write) using the properties of this RB class which starts with a "p".

pStatusString as string
property, URLAccess Mi, 4. Sep 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: Allways "".
Function: The status string for this transfer.
Notes: URLAccess stores itself properties about this transfer which you can access (read and write) using the properties of this RB class which starts with a "p".

pTotalItems as integer
property, URLAccess Mi, 4. Sep 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: Allways "".
Function: How much items will be transferred.
Notes: URLAccess stores itself properties about this transfer which you can access (read and write) using the properties of this RB class which starts with a "p".

pURL as string
property, URLAccess Mi, 4. Sep 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: Allways "".
Function: The URL of this transfer.
Notes: URLAccess stores itself properties about this transfer which you can access (read and write) using the properties of this RB class which starts with a "p".

pUserName as string
property, URLAccess Mi, 4. Sep 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: Allways "".
Function: The user name for this transfer.
Notes: URLAccess stores itself properties about this transfer which you can access (read and write) using the properties of this RB class which starts with a "p".

ReadAll as string
method, URLAccess Mi, 4. Sep 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: Allways "".
Function: Returns the current content of the download buffer if not downloading to a file or folder.
Notes: Lasterror is set.

ReplaceExisting as boolean
property, URLAccess Mi, 4. Sep 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: does nothing.
Function: Replace existing file?

ResourceFound
event, URLAccess Mi, 4. Sep 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: Never called.
Function: Indicates that the location specified by the URL reference has been accessed and is valid.

Result as string
property, URLAccess Mi, 4. Sep 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: Allways 0.
Function: If you downloaded to memory, the file content is in this string.

System
event, URLAccess Mi, 4. Sep 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: Never called.
Function: A system event occured.
Notes: Currently there is no plugin function available to tell Realbasic about this.

TransactionComplete
event, URLAccess Mi, 4. Sep 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: Never called.
Function: Indicates that an error occurred during data transfer.

TransactionComplete
event, URLAccess Mi, 4. Sep 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: Never called.
Function: Indicates that a download or upload operation is complete.

Upload
method, URLAccess Mi, 4. Sep 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: does nothing.
Function: Uploads a file.
Notes:
The property URL represents the URL to which a file or directory is to be uploaded. If you wish to replace the destination directory of this URL with the file or directory that you pass in the source parameter, terminate the string with a slash character (/), and set ReplaceExisting=true. If you specify a name that already exists on the server and do not specify ReplaceExisting=True, Upload returns the result code kURLDestinationExistsError (-30772) in the lasterror property. If you do not specify a name, do not specify ReplaceExistingFlag=true, and the name already exists on the server, the URL Access Manager creates a unique name by appending a number to the original name before the extension, if any. For example, if the URL specifies a file named file.txt, URLSimpleUpload changes the filename to file1.txt.

This function does not return until the upload is complete.
See the lasterror property for the error code returned.

When Download downloads data from a URL that represents a local file (that is, a URL that begins with file:///), the data fork is downloaded but the resource fork is not.

In Mac OS 8.6, if the file type of the file to be uploaded is unknown, Upload assumes that the file is of type text. In this case, the end-of-line character is changed to the Mac style end-of-line character 0x0d0x0a. In Mac OS 9, when a file of unknown type is uploaded, Upload does not assume that it is a text file. Instead, it identifies it as an unknown file type and does not change the end-of-line character.

Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 8.1 or later.

Uploading
event, URLAccess Mi, 4. Sep 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: Never called.
Function: Indicates that an upload operation is in progress.

URL as string
property, URLAccess Mi, 4. Sep 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: Allways "".
Function: An URL string.

Contact

Written 2002 by Christian Schmitz. Feel free to ask or report mistakes to realbasic@macsw.de.
Thanks.

This resource fork intentionally left blank ˇˇ